<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.13.2"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>CAD_Doc: Matchers Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  $(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">CAD_Doc<span id="projectnumber">&#160;1.0</span>
   </div>
   <div id="projectbrief">cad synopsis</div>
  </td>
    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.13.2 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){initNavTree('md__build_2__deps_2googletest-src_2docs_2reference_2matchers.html',''); initResizable(true); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">Matchers Reference</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="autotoc_md251"></a></p>
<p>A <b>matcher</b> matches a <em>single</em> argument. You can use it inside <code>ON_CALL()</code> or <code>EXPECT_CALL()</code>, or use it to validate a value directly using two macros:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Macro   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>EXPECT_THAT(actual_value, matcher)</code>   </td><td class="markdownTableBodyLeft">Asserts that <code>actual_value</code> matches <code>matcher</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ASSERT_THAT(actual_value, matcher)</code>   </td><td class="markdownTableBodyLeft">The same as <code>EXPECT_THAT(actual_value, matcher)</code>, except that it generates a <b>fatal</b> failure.   </td></tr>
</table>
<p>{: .callout .warning} <b>WARNING:</b> Equality matching via <code>EXPECT_THAT(actual_value, expected_value)</code> is supported, however note that implicit conversions can cause surprising results. For example, <code>EXPECT_THAT(some_bool, "some string")</code> will compile and may pass unintentionally.</p>
<p><b>BEST PRACTICE:</b> Prefer to make the comparison explicit via <code>EXPECT_THAT(actual_value, Eq(expected_value))</code> or <code>EXPECT_EQ(actual_value,
expected_value)</code>.</p>
<p>Built-in matchers (where <code>argument</code> is the function argument, e.g. <code>actual_value</code> in the example above, or when used in the context of <code>EXPECT_CALL(mock_object, method(matchers))</code>, the arguments of <code>method</code>) are divided into several categories. All matchers are defined in the <code>testing</code> namespace unless otherwise noted.</p>
<h1><a class="anchor" id="autotoc_md252"></a>
Wildcard</h1>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>_</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> can be any value of the correct type.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>A&lt;type&gt;()</code> or <code>An&lt;type&gt;()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> can be any value of type <code>type</code>.   </td></tr>
</table>
<h1><a class="anchor" id="autotoc_md253"></a>
Generic Comparison</h1>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Eq(value)</code> or <code>value</code>   </td><td class="markdownTableBodyLeft"><code>argument == value</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Ge(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument &gt;= value</code>    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Gt(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument &gt; value</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Le(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument &lt;= value</code>    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Lt(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument &lt; value</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Ne(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument != value</code>    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>IsFalse()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> evaluates to <code>false</code> in a Boolean context.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>IsTrue()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> evaluates to <code>true</code> in a Boolean context.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>IsNull()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>NULL</code> pointer (raw or smart).    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>NotNull()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a non-null pointer (raw or smart).    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Optional(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is <code>optional&lt;&gt;</code> that contains a value matching <code>m</code>. (For testing whether an <code>optional&lt;&gt;</code> is set, check for equality with <code>nullopt</code>. You may need to use <code>Eq(nullopt)</code> if the inner type doesn't have <code>==</code>.)    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>VariantWith&lt;T&gt;(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is <code>variant&lt;&gt;</code> that holds the alternative of type T with a value matching <code>m</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Ref(variable)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a reference to <code>variable</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>TypedEq&lt;type&gt;(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> has type <code>type</code> and is equal to <code>value</code>. You may need to use this instead of <code>Eq(value)</code> when the mock function is overloaded.   </td></tr>
</table>
<p>Except <code>Ref()</code>, these matchers make a <em>copy</em> of <code>value</code> in case it's modified or destructed later. If the compiler complains that <code>value</code> doesn't have a public copy constructor, try wrap it in <code>std::ref()</code>, e.g. <code>Eq(std::ref(non_copyable_value))</code>. If you do that, make sure <code>non_copyable_value</code> is not changed afterwards, or the meaning of your matcher will be changed.</p>
<p><code>IsTrue</code> and <code>IsFalse</code> are useful when you need to use a matcher, or for types that can be explicitly converted to Boolean, but are not implicitly converted to Boolean. In other cases, you can use the basic <a href="assertions.md#boolean"><code>EXPECT_TRUE</code> and <code>EXPECT_FALSE</code></a> assertions.</p>
<h1><a class="anchor" id="FpMatchers"></a>
Floating-Point Matchers</h1>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>DoubleEq(a_double)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>double</code> value approximately equal to <code>a_double</code>, treating two NaNs as unequal.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>FloatEq(a_float)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>float</code> value approximately equal to <code>a_float</code>, treating two NaNs as unequal.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>NanSensitiveDoubleEq(a_double)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>double</code> value approximately equal to <code>a_double</code>, treating two NaNs as equal.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>NanSensitiveFloatEq(a_float)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>float</code> value approximately equal to <code>a_float</code>, treating two NaNs as equal.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>IsNan()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is any floating-point type with a NaN value.   </td></tr>
</table>
<p>The above matchers use ULP-based comparison (the same as used in googletest). They automatically pick a reasonable error bound based on the absolute value of the expected value. <code>DoubleEq()</code> and <code>FloatEq()</code> conform to the IEEE standard, which requires comparing two NaNs for equality to return false. The <code>NanSensitive*</code> version instead treats two NaNs as equal, which is often what a user wants.</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>DoubleNear(a_double, max_abs_error)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>double</code> value close to <code>a_double</code> (absolute error &lt;= <code>max_abs_error</code>), treating two NaNs as unequal.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>FloatNear(a_float, max_abs_error)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>float</code> value close to <code>a_float</code> (absolute error &lt;= <code>max_abs_error</code>), treating two NaNs as unequal.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>NanSensitiveDoubleNear(a_double, max_abs_error)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>double</code> value close to <code>a_double</code> (absolute error &lt;= <code>max_abs_error</code>), treating two NaNs as equal.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>NanSensitiveFloatNear(a_float, max_abs_error)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>float</code> value close to <code>a_float</code> (absolute error &lt;= <code>max_abs_error</code>), treating two NaNs as equal.   </td></tr>
</table>
<h1><a class="anchor" id="autotoc_md254"></a>
String Matchers</h1>
<p>The <code>argument</code> can be either a C string or a C++ string object:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>ContainsRegex(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> matches the given regular expression.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>EndsWith(suffix)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> ends with string <code>suffix</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>HasSubstr(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> contains <code>string</code> as a sub-string.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>IsEmpty()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is an empty string.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>MatchesRegex(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> matches the given regular expression with the match starting at the first character and ending at the last character.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>StartsWith(prefix)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> starts with string <code>prefix</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>StrCaseEq(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is equal to <code>string</code>, ignoring case.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>StrCaseNe(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is not equal to <code>string</code>, ignoring case.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>StrEq(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is equal to <code>string</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>StrNe(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is not equal to <code>string</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>WhenBase64Unescaped(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a base-64 escaped string whose unescaped string matches <code>m</code>.   </td></tr>
</table>
<p><code>ContainsRegex()</code> and <code>MatchesRegex()</code> take ownership of the <code>RE</code> object. They use the regular expression syntax defined <a href="../advanced.md#regular-expression-syntax">here</a>. All of these matchers, except <code>ContainsRegex()</code> and <code>MatchesRegex()</code> work for wide strings as well.</p>
<h1><a class="anchor" id="autotoc_md255"></a>
Container Matchers</h1>
<p>Most STL-style containers support <code>==</code>, so you can use <code>Eq(expected_container)</code> or simply <code>expected_container</code> to match a container exactly. If you want to write the elements in-line, match them more flexibly, or get more informative messages, you can use:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>BeginEndDistanceIs(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a container whose <code>begin()</code> and <code>end()</code> iterators are separated by a number of increments matching <code>m</code>. E.g. <code>BeginEndDistanceIs(2)</code> or <code>BeginEndDistanceIs(Lt(2))</code>. For containers that define a <code>size()</code> method, <code>SizeIs(m)</code> may be more efficient.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ContainerEq(container)</code>   </td><td class="markdownTableBodyLeft">The same as <code>Eq(container)</code> except that the failure message also includes which elements are in one container but not the other.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Contains(e)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> contains an element that matches <code>e</code>, which can be either a value or a matcher.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Contains(e).Times(n)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> contains elements that match <code>e</code>, which can be either a value or a matcher, and the number of matches is <code>n</code>, which can be either a value or a matcher. Unlike the plain <code>Contains</code> and <code>Each</code> this allows to check for arbitrary occurrences including testing for absence with <code>Contains(e).Times(0)</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Each(e)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a container where <em>every</em> element matches <code>e</code>, which can be either a value or a matcher.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ElementsAre(e0, e1, ..., en)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> has <code>n + 1</code> elements, where the <em>i</em>-th element matches <code>ei</code>, which can be a value or a matcher.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>ElementsAreArray({e0, e1, ..., en})</code>, <code>ElementsAreArray(a_container)</code>, <code>ElementsAreArray(begin, end)</code>, <code>ElementsAreArray(array)</code>, or <code>ElementsAreArray(array, count)</code>   </td><td class="markdownTableBodyLeft">The same as <code>ElementsAre()</code> except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>IsEmpty()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is an empty container (<code>container.empty()</code>).    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>IsSubsetOf({e0, e1, ..., en})</code>, <code>IsSubsetOf(a_container)</code>, <code>IsSubsetOf(begin, end)</code>, <code>IsSubsetOf(array)</code>, or <code>IsSubsetOf(array, count)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> matches <code>UnorderedElementsAre(x0, x1, ..., xk)</code> for some subset <code>{x0, x1, ..., xk}</code> of the expected matchers.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>IsSupersetOf({e0, e1, ..., en})</code>, <code>IsSupersetOf(a_container)</code>, <code>IsSupersetOf(begin, end)</code>, <code>IsSupersetOf(array)</code>, or <code>IsSupersetOf(array, count)</code>   </td><td class="markdownTableBodyLeft">Some subset of <code>argument</code> matches <code>UnorderedElementsAre(</code>expected matchers<code>)</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Pointwise(m, container)</code>, <code>Pointwise(m, {e0, e1, ..., en})</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> contains the same number of elements as in <code>container</code>, and for all i, (the i-th element in <code>argument</code>, the i-th element in <code>container</code>) match <code>m</code>, which is a matcher on 2-tuples. E.g. <code>Pointwise(Le(), upper_bounds)</code> verifies that each element in <code>argument</code> doesn't exceed the corresponding element in <code>upper_bounds</code>. See more detail below.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>SizeIs(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a container whose size matches <code>m</code>. E.g. <code>SizeIs(2)</code> or <code>SizeIs(Lt(2))</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>UnorderedElementsAre(e0, e1, ..., en)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> has <code>n + 1</code> elements, and under <em>some</em> permutation of the elements, each element matches an <code>ei</code> (for a different <code>i</code>), which can be a value or a matcher.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>UnorderedElementsAreArray({e0, e1, ..., en})</code>, <code>UnorderedElementsAreArray(a_container)</code>, <code>UnorderedElementsAreArray(begin, end)</code>, <code>UnorderedElementsAreArray(array)</code>, or <code>UnorderedElementsAreArray(array, count)</code>   </td><td class="markdownTableBodyLeft">The same as <code>UnorderedElementsAre()</code> except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>UnorderedPointwise(m, container)</code>, <code>UnorderedPointwise(m, {e0, e1, ..., en})</code>   </td><td class="markdownTableBodyLeft">Like <code>Pointwise(m, container)</code>, but ignores the order of elements.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>WhenSorted(m)</code>   </td><td class="markdownTableBodyLeft">When <code>argument</code> is sorted using the <code>&lt;</code> operator, it matches container matcher <code>m</code>. E.g. <code>WhenSorted(ElementsAre(1, 2, 3))</code> verifies that <code>argument</code> contains elements 1, 2, and 3, ignoring order.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>WhenSortedBy(comparator, m)</code>   </td><td class="markdownTableBodyLeft">The same as <code>WhenSorted(m)</code>, except that the given comparator instead of <code>&lt;</code> is used to sort <code>argument</code>. E.g. <code>WhenSortedBy(std::greater(), ElementsAre(3, 2, 1))</code>.   </td></tr>
</table>
<p><b>Notes:</b></p>
<ul>
<li>These matchers can also match:<ol type="1">
<li>a native array passed by reference (e.g. in <code>Foo(const int (&amp;a)[5])</code>), and</li>
<li>an array passed as a pointer and a count (e.g. in <code>Bar(const T* buffer,
        int len)</code> &ndash; see <a class="el" href="#MultiArgMatchers">Multi-argument Matchers</a>).</li>
</ol>
</li>
<li>The array being matched may be multi-dimensional (i.e. its elements can be arrays).</li>
<li><p class="startli"><code>m</code> in <code>Pointwise(m, ...)</code> and <code>UnorderedPointwise(m, ...)</code> should be a matcher for <code>::std::tuple&lt;T, U&gt;</code> where <code>T</code> and <code>U</code> are the element type of the actual container and the expected container, respectively. For example, to compare two <code>Foo</code> containers where <code>Foo</code> doesn't support <code>operator==</code>, one might write:</p>
<p class="startli"><code>cpp MATCHER(FooEq, "") { return std::get&lt;0&gt;(arg).Equals(std::get&lt;1&gt;(arg)); } ... EXPECT_THAT(actual_foos, Pointwise(FooEq(), expected_foos)); </code></p>
</li>
</ul>
<h1><a class="anchor" id="autotoc_md256"></a>
Member Matchers</h1>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Field(&amp;class::field, m)</code>   </td><td class="markdownTableBodyLeft"><code>argument.field</code> (or <code>argument-&gt;field</code> when <code>argument</code> is a plain pointer) matches matcher <code>m</code>, where <code>argument</code> is an object of type <em>class</em>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Field(field_name, &amp;class::field, m)</code>   </td><td class="markdownTableBodyLeft">The same as the two-parameter version, but provides a better error message.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Key(e)</code>   </td><td class="markdownTableBodyLeft"><code>argument.first</code> matches <code>e</code>, which can be either a value or a matcher. E.g. <code>Contains(Key(Le(5)))</code> can verify that a <code>map</code> contains a key <code>&lt;= 5</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Pair(m1, m2)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is an <code>std::pair</code> whose <code>first</code> field matches <code>m1</code> and <code>second</code> field matches <code>m2</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>FieldsAre(m...)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a compatible object where each field matches piecewise with the matchers <code>m...</code>. A compatible object is any that supports the <code>std::tuple_size&lt;Obj&gt;</code>+<code>get&lt;I&gt;(obj)</code> protocol. In C++17 and up this also supports types compatible with structured bindings, like aggregates.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Property(&amp;class::property, m)</code>   </td><td class="markdownTableBodyLeft"><code>argument.property()</code> (or <code>argument-&gt;property()</code> when <code>argument</code> is a plain pointer) matches matcher <code>m</code>, where <code>argument</code> is an object of type <em>class</em>. The method <code>property()</code> must take no argument and be declared as <code>const</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Property(property_name, &amp;class::property, m)</code>   </td><td class="markdownTableBodyLeft">The same as the two-parameter version, but provides a better error message.   </td></tr>
</table>
<p><b>Notes:</b></p>
<ul>
<li><p class="startli">You can use <code>FieldsAre()</code> to match any type that supports structured bindings, such as <code>std::tuple</code>, <code>std::pair</code>, <code>std::array</code>, and aggregate types. For example:</p>
<p class="startli">```cpp std::tuple&lt;int, std::string&gt; my_tuple{7, "hello world"}; EXPECT_THAT(my_tuple, FieldsAre(Ge(0), HasSubstr("hello")));</p>
<p class="startli">struct MyStruct { int value = 42; std::string greeting = "aloha"; }; MyStruct s; EXPECT_THAT(s, FieldsAre(42, "aloha")); ```</p>
</li>
<li>Don't use <code>Property()</code> against member functions that you do not own, because taking addresses of functions is fragile and generally not part of the contract of the function.</li>
</ul>
<h1><a class="anchor" id="autotoc_md257"></a>
Matching the Result of a Function, Functor, or Callback</h1>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>ResultOf(f, m)</code>   </td><td class="markdownTableBodyLeft"><code>f(argument)</code> matches matcher <code>m</code>, where <code>f</code> is a function or functor.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ResultOf(result_description, f, m)</code>   </td><td class="markdownTableBodyLeft">The same as the two-parameter version, but provides a better error message.   </td></tr>
</table>
<h1><a class="anchor" id="autotoc_md258"></a>
Pointer Matchers</h1>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Address(m)</code>   </td><td class="markdownTableBodyLeft">the result of <code>std::addressof(argument)</code> matches <code>m</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Pointee(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> (either a smart pointer or a raw pointer) points to a value that matches matcher <code>m</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Pointer(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> (either a smart pointer or a raw pointer) contains a pointer that matches <code>m</code>. <code>m</code> will match against the raw pointer regardless of the type of <code>argument</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>WhenDynamicCastTo&lt;T&gt;(m)</code>   </td><td class="markdownTableBodyLeft">when <code>argument</code> is passed through <code>dynamic_cast&lt;T&gt;()</code>, it matches matcher <code>m</code>.   </td></tr>
</table>
<h1><a class="anchor" id="MultiArgMatchers"></a>
Multi-argument Matchers</h1>
<p>Technically, all matchers match a <em>single</em> value. A "multi-argument" matcher is just one that matches a <em>tuple</em>. The following matchers can be used to match a tuple <code>(x, y)</code>:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Eq()</code>   </td><td class="markdownTableBodyLeft"><code>x == y</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Ge()</code>   </td><td class="markdownTableBodyLeft"><code>x &gt;= y</code>    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Gt()</code>   </td><td class="markdownTableBodyLeft"><code>x &gt; y</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Le()</code>   </td><td class="markdownTableBodyLeft"><code>x &lt;= y</code>    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Lt()</code>   </td><td class="markdownTableBodyLeft"><code>x &lt; y</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Ne()</code>   </td><td class="markdownTableBodyLeft"><code>x != y</code>   </td></tr>
</table>
<p>You can use the following selectors to pick a subset of the arguments (or reorder them) to participate in the matching:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>AllArgs(m)</code>   </td><td class="markdownTableBodyLeft">Equivalent to <code>m</code>. Useful as syntactic sugar in <code>.With(AllArgs(m))</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Args&lt;N1, N2, ..., Nk&gt;(m)</code>   </td><td class="markdownTableBodyLeft">The tuple of the <code>k</code> selected (using 0-based indices) arguments matches <code>m</code>, e.g. <code>Args&lt;1, 2&gt;(Eq())</code>.   </td></tr>
</table>
<h1><a class="anchor" id="autotoc_md259"></a>
Composite Matchers</h1>
<p>You can make a matcher from one or more other matchers:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>AllOf(m1, m2, ..., mn)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> matches all of the matchers <code>m1</code> to <code>mn</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>AllOfArray({m0, m1, ..., mn})</code>, <code>AllOfArray(a_container)</code>, <code>AllOfArray(begin, end)</code>, <code>AllOfArray(array)</code>, or <code>AllOfArray(array, count)</code>   </td><td class="markdownTableBodyLeft">The same as <code>AllOf()</code> except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>AnyOf(m1, m2, ..., mn)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> matches at least one of the matchers <code>m1</code> to <code>mn</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>AnyOfArray({m0, m1, ..., mn})</code>, <code>AnyOfArray(a_container)</code>, <code>AnyOfArray(begin, end)</code>, <code>AnyOfArray(array)</code>, or <code>AnyOfArray(array, count)</code>   </td><td class="markdownTableBodyLeft">The same as <code>AnyOf()</code> except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Not(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> doesn't match matcher <code>m</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Conditional(cond, m1, m2)</code>   </td><td class="markdownTableBodyLeft">Matches matcher <code>m1</code> if <code>cond</code> evaluates to true, else matches <code>m2</code>.   </td></tr>
</table>
<h1><a class="anchor" id="autotoc_md260"></a>
Adapters for Matchers</h1>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>MatcherCast&lt;T&gt;(m)</code>   </td><td class="markdownTableBodyLeft">casts matcher <code>m</code> to type <code><a class="el" href="class_matcher.html">Matcher</a>&lt;T&gt;</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>SafeMatcherCast&lt;T&gt;(m)</code>   </td><td class="markdownTableBodyLeft"><a href="../gmock_cook_book.md#SafeMatcherCast">safely casts</a> matcher <code>m</code> to type <code><a class="el" href="class_matcher.html">Matcher</a>&lt;T&gt;</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Truly(predicate)</code>   </td><td class="markdownTableBodyLeft"><code>predicate(argument)</code> returns something considered by C++ to be true, where <code>predicate</code> is a function or functor.   </td></tr>
</table>
<p><code>AddressSatisfies(callback)</code> and <code>Truly(callback)</code> take ownership of <code>callback</code>, which must be a permanent callback.</p>
<h1><a class="anchor" id="MatchersAsPredicatesCheat"></a>
Using Matchers as Predicates</h1>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"><a class="el" href="class_matcher.html">Matcher</a>   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Matches(m)(value)</code>   </td><td class="markdownTableBodyLeft">evaluates to <code>true</code> if <code>value</code> matches <code>m</code>. You can use <code>Matches(m)</code> alone as a unary functor.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ExplainMatchResult(m, value, result_listener)</code>   </td><td class="markdownTableBodyLeft">evaluates to <code>true</code> if <code>value</code> matches <code>m</code>, explaining the result to <code>result_listener</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Value(value, m)</code>   </td><td class="markdownTableBodyLeft">evaluates to <code>true</code> if <code>value</code> matches <code>m</code>.   </td></tr>
</table>
<h1><a class="anchor" id="autotoc_md261"></a>
Defining Matchers</h1>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Macro   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>MATCHER(IsEven, "") { return (arg % 2) == 0; }</code>   </td><td class="markdownTableBodyLeft">Defines a matcher <code>IsEven()</code> to match an even number.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>MATCHER_P(IsDivisibleBy, n, "") { *result_listener &lt;&lt; "where the remainder is " &lt;&lt; (arg % n); return (arg % n) == 0; }</code>   </td><td class="markdownTableBodyLeft">Defines a matcher <code>IsDivisibleBy(n)</code> to match a number divisible by <code>n</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>MATCHER_P2(IsBetween, a, b, absl::StrCat(negation ? "isn't" : "is", " between ", PrintToString(a), " and ", PrintToString(b))) { return a &lt;= arg &amp;&amp; arg &lt;= b; }</code>   </td><td class="markdownTableBodyLeft">Defines a matcher <code>IsBetween(a, b)</code> to match a value in the range [<code>a</code>, <code>b</code>].   </td></tr>
</table>
<p><b>Notes:</b></p>
<ol type="1">
<li>The <code>MATCHER*</code> macros cannot be used inside a function or class.</li>
<li>The matcher body must be <em>purely functional</em> (i.e. it cannot have any side effect, and the result must not depend on anything other than the value being matched and the matcher parameters).</li>
<li>You can use <code>PrintToString(x)</code> to convert a value <code>x</code> of any type to a string.</li>
<li><p class="startli">You can use <code>ExplainMatchResult()</code> in a custom matcher to wrap another matcher, for example:</p>
<p class="startli"><code>cpp MATCHER_P(NestedPropertyMatches, matcher, "") { return ExplainMatchResult(matcher, arg.nested().property(), result_listener); } </code> </p>
</li>
</ol>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.13.2 </li>
  </ul>
</div>
</body>
</html>
